Cost and policy topic

What the glass costs, and the rungs below full glass.

The tiers

GlassTier is the rung: full glass, a flat translucent fill that captures nothing (GlassTier.cheap), or an opaque fill (GlassTier.opaque). The package never moves between them on its own; a GlassTierPolicy chooses from what the application knows:

GlassHost(
  backdrop: const Color(0xFF101014), // what the opaque tier fills with
  tier: GlassTierPolicy(
    reduceTransparency: reduceTransparency, // read natively by the app
    ceiling: lowEndDevice ? GlassTier.cheap : null,
  ).choose(),
  child: navigator!,
)

The device

Flutter does not pass on reduce transparency, contrast on macOS or the thermal state, and the package ships no platform code. Read them natively and declare them: GlassThermalState to GlassHost.thermal, GlassHardware to GlassHost.hardware. Hardware changes reported costs, never what is drawn.

The ledger

GlassLedger is the host's register of every glass on screen. Read it through GlassScope to get a GlassLoad: the count, the area, screens of glass, and a GlassLoadVerdict against what was measured on that hardware.

final GlassLoad? load = GlassScope.maybeOf(context)?.read(
  viewSize: MediaQuery.sizeOf(context),
  model: GlassHardware.detect().surfaceCostModel,
);
debugPrint('$load'); // GlassLoad(6 surfaces, 0.12 screens, withinMeasured)

The capture's resolution

The host chooses the downscale of its capture per finish, against measured quality tables: ProxyResolutionPolicy, ProxyResolution and the reason it gives, ProxyDivisorReason. Whether it may hold a capture nothing under the glass changed is GlassContentDeclaration; why it took one is RetakeReason.

Where the numbers come from

Every measured number in this reference was taken in a profile build on the device named, on Flutter 3.47.1: a Samsung Galaxy S25 Ultra (Adreno 830, Vulkan), an iPad Pro 11″ M2 (Metal), a Galaxy S22 Ultra (Xclipse 920) and a MacBook Pro M3 Max, between 2026-08-24 and 2026-09-26. The full table is in the README, and the raw digests in the repository's provenance/.

Classes

GlassLedger Cost and policy
The register of glass surfaces on one screen.
GlassLoad Cost and policy
What the register says, read against one platform's measurements.
GlassScope Cost and policy
Carries one GlassLedger down the tree.
GlassSurfaceCluster Cost and policy
A set of surfaces whose silhouettes are one shape.
GlassSurfaceGeometry Cost and policy
Something in the render tree that can say where it is.
GlassSurfaceRecord Cost and policy
One glass surface, read at the moment it was asked.
GlassThermalPolicy Cost and policy
What the retake may spend on staleness under thermal pressure — the thermal lever, and a policy rather than a panic.
GlassTierChoice Cost and policy
One rung and the reason it holds.
GlassTierPolicy Cost and policy
Turns whatever an application knows into one rung.
ProxyResolution Cost and policy
The proxy's recording resolution, as an integer divisor of the device pixel ratio.
ProxyResolutionChoice Cost and policy
What the chooser decided, and enough to argue with it.
ProxyResolutionPolicy Cost and policy
Chooses the divisor.

Enums

GlassContentDeclaration Cost and policy
Whether the host may hold a proxy that nothing it watches has changed.
GlassHardware Cost and policy
The device family whose measurements apply.
GlassLoadVerdict Cost and policy
Where a screen's glass sits against the runs that exist.
GlassSurfaceCostModel Cost and policy
Which platform's measurements to read the register against.
GlassThermalState Cost and policy
Thermal pressure, in Apple's four names — the coarser vocabulary of the two, so every Android status maps onto one of them and none of Apple's is invented.
GlassTier Cost and policy
What a surface paints. The rungs of phase D's ladder, in order of what they draw rather than of what they cost.
GlassTierReason Cost and policy
Why the rung in force is the one in force.
ProxyBlurPass Cost and policy
How the residual blur reaches the atlas.
ProxyCostModel Cost and policy
How the hardware charges for a capture — which decides whether resolution is a lever at all.
ProxyDivisorReason Cost and policy
Why the chooser stopped where it did.
RetakeReason Cost and policy
Why the oracle decided what it decided.

Typedefs

ProxyDamage = ({double deltaE, bool measured}) Cost and policy
A damage figure, and whether it is a reading or a bound.
ProxyRouteCost = ({double factor, bool measured}) Cost and policy
What the whole route costs at a divisor, relative to the same route at full resolution — and whether that point was measured or interpolated between two that were.